/**
 * API版本生命周期管理配置
 * 基于大厂最佳实践的版本策略
 */

module.exports = {
  // 版本生命周期阶段
  LIFECYCLE_STAGES: {
    DEVELOPMENT: 'development',    // 开发阶段
    ALPHA: 'alpha',               // 内部测试
    BETA: 'beta',                 // 公开测试
    STABLE: 'stable',             // 稳定版本
    DEPRECATED: 'deprecated',     // 已弃用
    SUNSET: 'sunset'              // 即将下线
  },

  // 版本策略配置
  VERSION_STRATEGY: {
    // 语义化版本控制
    semantic_versioning: true,
    
    // 版本号格式: major.minor.patch
    version_format: 'major.minor.patch',
    
    // URL中只显示主版本号
    url_major_only: true,
    
    // 支持的版本列表
    supported_versions: [
      {
        version: 'v1',
        full_version: '1.0.0',
        status: 'deprecated',
        release_date: '2023-01-01',
        deprecation_date: '2024-01-01',
        sunset_date: '2024-12-31'
      },
      {
        version: 'v2',
        full_version: '2.0.0',
        status: 'stable',
        release_date: '2024-01-01',
        maintenance_until: '2025-12-31'
      },
      {
        version: 'v3',
        full_version: '3.0.0-beta',
        status: 'beta',
        release_date: '2024-06-01',
        expected_stable: '2024-09-01'
      }
    ]
  },

  // 向后兼容策略
  COMPATIBILITY_POLICY: {
    // 最小支持期限
    minimum_support_period: '18 months',
    
    // 弃用通知期
    deprecation_notice_period: '6 months',
    
    // 过渡期（从弃用到下线）
    sunset_transition_period: '12 months',
    
    // 兼容性保证
    backward_compatibility: {
      data_format: 'best_effort',      // 数据格式尽力兼容
      api_endpoints: 'guaranteed',     // API端点保证兼容
      authentication: 'guaranteed',   // 认证方式保证兼容
      rate_limiting: 'policy_change'  // 限流策略可能变化
    }
  },

  // 错误处理策略
  ERROR_HANDLING: {
    version_not_supported: {
      status: 400,
      code: 'VERSION_NOT_SUPPORTED',
      message: 'The requested API version is not supported',
      suggestion: 'Please use a supported version'
    },
    version_deprecated: {
      status: 200,  // 仍然成功，但添加警告
      warning: 'API_VERSION_DEPRECATED',
      message: 'This API version is deprecated and will be removed',
      migration_info: true
    },
    version_sunset: {
      status: 410,  // Gone
      code: 'VERSION_SUNSET',
      message: 'This API version has been discontinued',
      alternatives: true
    }
  },

  // 监控和分析
  MONITORING: {
    // 版本使用统计
    track_version_usage: true,
    
    // 弃用版本警告日志
    log_deprecated_usage: true,
    
    // 性能监控按版本分组
    performance_metrics_by_version: true,
    
    // 用户迁移进度跟踪
    migration_progress_tracking: true
  },

  // 文档和通信策略
  DOCUMENTATION: {
    // 版本文档结构
    version_docs_pattern: '/docs/api/{version}/',
    
    // 迁移指南
    migration_guide_pattern: '/docs/migration/{from}-to-{to}',
    
    // 变更日志
    changelog_pattern: '/docs/changelog/{version}',
    
    // 通知渠道
    notification_channels: [
      'api_headers',           // HTTP头中的警告
      'developer_portal',      // 开发者门户公告
      'email_notifications',   // 邮件通知
      'webhook_notifications'  // Webhook通知
    ]
  }
};